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XEROX 
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This memo is the specification for a new user interface for the Mesa 5.0 debugger; it has been 
drawn together from suggestions from the Mesa task list, Greg Shaw's suggestion list (based on the 
experience of ElM), tlie change requests classified as debugger wishes, experiments with the Tools 
Environment and the SmallTalk Browser, and discussion with experienced Mesa users. 

The design is based on the following observations and goals: 

* We are aiming for the experienced systems programmer, not a clerical person with minimal 
training who will quit in 6 months. 

* We must build on the capabilities (and code) of the current Mesa debugger as well as 
maintaining the present Mesa style of debugging. 

* Speeding up the performance and increasing reliabihty is as important as improving the 
interface. 

* We should try to cut down on tlie cdit-compile-debug loop as much as possible. 
Keep it simple. 



* 



The basic facilities of the debugger can be divided into the following categories: setting 
breakpoints and tracing program execution, examining (and changing) the runtime state, setting the 
context in which user symbols are looked up, directing program control, and a collection of less 
frequently used low-level utility commands. By supplementing the present teletype command 
processor interface to these facilities with more window/selcction/menu based capabilities, we can 
both speed up and ease the debugging process. 

The new debugger interface looks as follows: 

* The debugger is initialized with 3 windows: debug.typescript window, a sourcefile 
window, and a window for manipulating the stack (debug.sTACK). 

* Each of these windows has a menu containing the standard set of window operations: MOVE 
(change the position of the window), GROW (change the size of the window), BIG (make the window as large 
as the entire screen /restore), and SMALL (make the window as into a small window at the side of the screen). 
ITie menu also contains the basic selection operations that arc common to all windows: 
STUFF rr (stuffs the selection of the window into the keyboard stream of Uie DEBUG.TYPESCRIPT 
window), FIND (finds the next occurence of the selection in the window). 

* Each window has its associated filename in tlie header of the window. 
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* Each window may have a selection, but only one selection is "the current selection" at any 
time. This simplifies input to commands that involve using the current selection. 

* llie mouse buttons remain as before: RED selects and extends the selection by characters, 
YELLOW selects and extends the selection by words, and blue displays the menu. 

* The scrolling functions remain as before: red for scrolling up, yellow for thumbing, 
BLUE for scrolling down, and yellow/blue for noimalizing tlie selection. Possible 
enhancements to the present capabilities are to have continuous scrolling and split windows. 

* Look into what is involved in adopting the Tools window/menu/selection/editor package. 
Debug.Typescript window: 

* Retains the present debugger interface capabilities with respect to typing in key letters for 
invoking commands. 

* Is the only debugger-created window that accepts type-in. This means that the stuff-it key can 
continue put characters into the input stream of this window; thus typing a character (when a non-scratchfile 
window is current) makes this typescript window Uie current window. 

* Used to interpret expressions. 

* The place of all debugger to user COmmuncation. This window is used for reporting uncaught 
signals, error messages from the interpreter, and saving lists of information (such as List Breaks or Display 
GlobalFrameTable). 

* In addition to the standard window operations, the menu for this window has a command 
to allow you to create a new scratch window. 

* The Debug.Typescript file can still be viewed as a log of the debugging session, if a user 
wishes to save some of the information that is lost by using selections instead of typing in all of the 
commands, you can record infonnation hi this window (in the form of comments) or use die old type-in 
command processor. 

Sourcefile window: 

* Used to set breakpoints and for displaying the source position when looking at the stack. 

* This window is the only window in which you may set breakpoints. These breakpoint 
commands enable the user to perform all of the present breakpoint operations simply by 
selecting the location and choosing the appropriate menu command. 



llie semantics of the breakpoint 



Keyword 


Selection 


BREAK 


PROCEDURE 




RETURN 




source 


CBREAK 


PROCEDURE 




RETURN 




source 


CLEAR 


PROCEDURE 




Riri'URN 




source 


BR ALL 


PROCEDURE 




RETURN 


CL ALL 


PR0CIU3URE 




REl'URN 




PROGRAM 



commands are as follows: 
Action (old command) 
Break Entry 
Break Xit 

Break Procedure, Break Module 
same as above commands but must 
specify condition as post-operator 

Clear Entry Break 

Clear Xit Break 

Clear Break, Clear Module Break 

Break All Entries 

Break All Xits 

Clear All Entries 

Clear All Xits 

Clear All Breaks 
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This scheme allows us to set conditional breakpoints by selecting the location, invoking the 
CBREAK command, and then typing in the condition. Where: either a window pops up (it is nice 
for this infottnalion and its window to go away after being input) or into the typescript window (which is 
already there but possibly not visible)? See figure 1. 

The type of menu to be used is as yet undetermined; either a menu with die breakpoint commands in addition 
to the window commands (as in the present scheme) or perhaps a fixed menu consisting of the keywords 
BREAK, CLFAR, CONDITION, and ALL, loaited either in the header of the window along with the file 
name or on the bottom of tlie window, tliat allows combinations of keywords to be selected, widi BREAK and 
CLEAR actually activating tlie action. More experimenting and discussion is still neccesary to resolve tliis. 

All breakpoints are shown by a graphic indication in the source file window. What to use: 
secondary selection highlighdng, or a carat beneath the location? This means the window needs to be refreshed 
(somehow) each time any breakpoint is set or cleared. 

Selections in the breakpoint window resolve only to places where breakpoints are allowed 
to be set (according to the compiler-generated fine grain table). 



Dcbug.stack: 



The stack window is used for displaying current context information as well as the 
procedure call stack. Whichever level of the stack is selected becomes the current context 
for symbol lookup. It possible to change the current context by moving the selection in 
either direction along the stack. 

A subwindow of the stack window is reserved for showing context information about the 
current configuration, psb, module, global frame, and local frame, llie rest of this 
subwindow is used to show the procedure call stack, one level at a time. If you wish to 
advance along the stack, select the next menu command or hit the next key. How about 
using the LF key for the next key? You may go back up the Stack by selecting the name at the 
level you wish to look at. How to do jump (as in skip the next n levels)? 

The rest of the stack window is used to show the variables local to the current context. 
Should this be two separate windows? Should the variable window be cleared for each SHOW or just 
scrolled? lliis subwindow has its own scrolling capabilities; stack commands are activated by 
means of a menu. See figures 2 and 3 for examples. ITie semantics of the commands are as 
follows: 



r, w 



Keyword 


Selection 


Action (old command) 


SHOW 


config 


Display Configuration 




psb 


Display Process - p, 




module 


Display Module - v 




procedure 


Display Stack - v 


SOURCE 


module 


Display Module - s 




procedure 


Display Stack - s 




psb 


Display Process - s 


NEXT 


procedure 


Display Stack - n 




psb 


Display Process - n 



This window may also be used for changing the context. Selecting one of the context 
keywords (Configuration, Process, Module) means "change this context". When the 
current context gels modified in some way, all of the context information gets updated See 
die section below for details. 

The stack window does not allow user type-in. Updating gets done by the debugger when 
the context gels modified in some way. Only word selection is allowed in this window, 
since selections are only used for context setting puiposes. Note iliat all messages like "No 
symbols for nnnnnB..." and "Source file, mesa not available" continue to be displayed in the 
DliBUG.T YPI{SC1< [PT window. 
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Changing the context: 

* If you wish to change the context, select one of the context keywords. A (temporary) 
window (or call it a "view") appears with a list of the choices. Selecting the name changes the 
context as well as updating all of the corresponding information in the context status 
subwindow. 

* If you select the keyword "Configuration", a window appears, called "List.configs", 
consisting of a Hst of all the configurations that have been loaded. Note that this is the same 
output as the present List Configurations command. 

* If you select the keyword "Module", a window appears, called "List. modules", consisting 
of a list of the names of all of the modules in the current configuration. Note that this is 
similar to the output of the present Display Configuration command. See figure 4 for an example. 

* If you select the keyword "Process", a window appears, called "List. processes", 

consisting of a list of all processes by ProceSsHandle. What other information is neccesary in 
order for this to be interesting: frame, root, source, priority? 

Directing program control: 

* Explore the idea of using the header of the DEBUG.TYPnSCRIPT window to contain a menu of the 
PROCEED, QUIT, and KILL commands in order to have a menu way of directing program control. 

Scratch window: 

* The menu for this type of window has the standard window operations in addition to 
commands to create a new scratch window, destroy a scratch window, and load a file 
into a scratch window. 

* This type of window can also accept keyboard type-in. 
Mode changes: 

* ITie debugger keeps a "property sheet" of state information that is not Hkely to change 
often. When you wish to examine or change any of these modes, you invoke the Mode 
Change command. This causes a window to appear (like the specification of a Tool or a property 
sheet in Desktop) in which you can reverse a mode by selecting on/oit\ This command is 
used to set global state information that is currently maintained by the commands CAse 
on/off, Worry on/off, Keys on/off. What to call this command and how to invoke and display it? 
We should look into the possibility of extending this sheet to include other options (for example, whether you 
would like to have records displayed with spaces or carriage returns between the fields). 

Consistent rules for invoking commands: 

* In general, the commands that require no parameters (Userscreen), print many lines of 
information (Coremap), take more time to complete (List Processes), change the state 
{Reset Context), and direct program control (Proceed) are the types of commands that 
require confirmation (CR) before they are executed. 

* Menu commands with just one operand use the current selection as the object of the action, 
and activate when the menu button is let up. 

* Menu commands that require two arguments (such as conditional breakpoints), use the 
current selection as the first argument and prompt (how?) for the second one when the menu 
button is let up. 

* All octal commands (Octal Read, Write, Set break, Clear break, Set Octal Context) may 
be invoked only through the command processor, llie same applies for other low-level 
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utility commands. 

Changes to the way things are now: 

* As a result of implementing more selection based schemes for invoking debugger 
commands, WindEx has to become a standard part of the Mesa debugger. 



* 



The need for the mesa.typescript window has gone away, so this feature is no longer 
supported. 

Different types of windows have their own menu commands in addition to the basic set of 
window operations. 

The distinction between the old form of tracepoints and breakpoints has almost disappeared 
with the new display stack mode. Therefore only breakpoints are now being supported, 
with tracepoints being reserved for future design in combination with a macro facility. You 
would like to be able to specify a set of actions to be performed (including the ability to proceed) when 
reaching a tracepoint, without the user having to be there to type in the commands. 

ITie functions of the Display Variable and Interpret commands in Mesa 4.0 debugger have 
been superceded by the interpreter and therefore are no longer supported. 






bbptr: bitbUDefs.Bbptr = EVEN[BA3Erbbtable]]; 
niapaddr: BMptr ^ rectangle. bitmap. addri 
wordsperline: CARDINAL = rectangle. bitmap. wordsperlinej 
dlx: xCoord <- rectangle. x0+x0j; 
dty: yCoord <• rectangle. yf^ 



dw; xCoord ^ MIN[rectangl 
dh: yCoord ^ MIN[rectangl 
bbptrt <r [0, FALSE, FALSE 
rline, 

dlx, dty, d'.',s d h, mapad 
BitBltDefs.^SiaSlEbbptr].; 






8^MiSB«i^pRe(tt|^ri9ite 



yetJumpStripe 

DoWork 

ViMndowExecutive 



Uonf iguration: XDebug 
PSB: 2337B 
Module: RectanglesA 
6: 172570B, L: 1643286 



wordspe 






ClearBoxInRectangle, L: i64328B (in Rectanql 
A, G;172570B) 
>rectangle=160737Bt 

X0 = 1 

width=9 

y0=13 

height=434 

gray=164124Bt 

bbtable=(17)[ 1, 14B, . . . , 0] 

bbptr==164252Bt 

mapaddr=122000Bt 

wordsperl ine=40B 



es 






ClearboxInRectanqle, L: 164230b (in RectanglesA, G:172570B) 
Source: <>BitBltDefs.BITBLT[bbptr]; 

> Proceed [confirm] 
*** interrupt *** 
>tUserProc [confirm] 
Proc: Press- 
Press file name: duil. press 
duil . press. . .D 



>s 



RM*^Mie:i?si^Mes'ai^jM^M^P^^ 






]i 



SV]J 



flag ^ NovaOps .Nova0utLd[0utLd,Core8wapLiefs.PuntInfot . pCoreFP, E8V 

REGISTER[WDCreg] <- savewdcj 
SELECT flag FROM 

=> NovaOps . HovaInLd[ InLd, CoreSwapDef s . Punt Inf ot . pDebuggerFP, E 

1 => level ^ ESV. level; 
ENDCASE => ESV. reason *• proceed; 

REGISTER[XTSreg] <• xferTrapStatus; 
SD[SDDefs.sXferTrap] ^ xferTrapHandler; 
EHDLOOP^ 



i'DlbfUttigat^^efc^^^i 



Configuration: 


XDebug 


PSB: 2332B 


Module; Resident 


G: 173760B, L: 


166740B 






PSB: 2332B, Menioryywap, L: 166/40B (in.Resi 
dent, GI173760B) 
>priority i 

root: WindowExecutive, L: 162024B (in WEM 
ain, G:116400B) 



[|S«ior^&*ap 



ParityProcess 

ProcessKeytaoard 

ReadChar 






m : 0, no log : 0, parti : 0, part2 : 4167B] , leaderDA : vDA[4316B] ] , fa : FA[ da : vDA[4412 
B ] 3 page : 31B, bvte : 0] ] , Ispaqes : 2, niapLoq : 14335026517Bt , mds : 26467B, f i 1 1 : (3) 

[ 0, 0, 0]] 

> Proceed [confirm] 

^*^** interrupt ^♦'•** 

>tLlserProc [confirm] 

Proc: Press 

Press file name: Duil. press 

Duil . press. » .D 



BitBUDefs.BITBLT[bbptr]i 
END; 

DrawBoxInRectangle! PUBLIC PROCEDURE [ 

rectangle! Rptr, x0, width: xCoord, y0, height: yCoord] = 

BEGIN 

bbtable: ARRAY [9. .SIZE[BitBUDefs.BBTable]] OF WORD; 

tataptr: BitBltDefs.BBptr = EVEN[BASE[tabtable]]; 

mapaddr: BMptr *• rectangle. bitmap. addr; 






Configuration : XDetaug 
PSB: 2337B 
Module: RectanglesA 
G: 172570B, L: 1643296 



(llffa^Ba3tSnKee.i^hme 



Set Jumps tripe 
DoWork 

WindowExecutive 
SetJumpStripe 



U I ear Box I nRectanqle, L: lb4cJi£UB (in Rectan 
glesA, G:172570&5 
>rectangle=160737Bt 

X0=1 

width=9 
y0=13 

height=434 
qray=164124Bt 

bbtable-(17)[ 1, 14B, . . . , 0] 
bbptr=164252B^ 
' rnapaddr=122000Bt 
wordsperline=40B 
dlx=l 






Rec t ang 1 e [ 1 1 nk : N I L , v i s i b 1 e ; T RUE , opt i ons : ROp t i ons [ Note I nv i s 1 b 1 e : F ALSE , No 

teOverf low : TRUE] , bitmap : 160757Bt, x0 ; 0, width : 512, cw : 512, y0 : S, heiqht : 448, 

ch;448] 

>Proceed [confirm] 

*^^* interrupt *** 

>tUserProc [confirm] 

Proc: Press 

Press file name: duil. press 

duil. press. . .D 



BitBltDefs.BITBLT[bbptrli 
END J 

DrawBoxInRectangle: PUBLIC PROCEDURE [ 

rectangle! Rptr, x8, width; xCoord, yS, height; yCoord] = 

BEGIN 

bbtable: ARRAY [9. . SIZE[BitBUDefs.BBTable]] OF WORD; 

bbptr; BitBltOefs.BBptr = EVEN[BASE[bbtable]]j 

mapaddr; BMptr * rectangle. bitmap. addrj 



Configuration: 


XDebi 


jg 


PSB: 23 


37B 








imEmmi 


Rec 


tangles A 








G: 1725 


70B, 


L: 


1643: 


20B 






ClearBoxInRectanct le, L: lb4cJk:LtB (in Rectan 
glesA, G:172570B3 
>rectangle=160737Bt 



•mstiK'i«ae{tfcT;-e#^»^ 



Strings 

Files 

StreamsA 

StreanisB 

FSP 



C 1 earBox I nRec tangle 

SetJumpStripe 

DoWork 

W i ndo wExecut i ve 

SetJumpStripe 



iimtangitesA 



RectanglesB 
Display 
Stream 10 



40B 






Rectang 1 e [ 1 i nk : N I L , v i s i b 1 e : TRUE , opt i cms ; Rup t i ons [ Mote I nv i s i b 1 e : F ALb:E , No 

teOverf low : TRUE ] .bitmap : 160757Bt , xQ : 0, width : 512, cw : 512, v0 : 8, height : 448 j 

ch:448] 

> Proceed [confirm] 

=*=** interrupt *=^*^ 

>tUserProc [confirm] 

Proc; Press 

Press file name: Dui2.press 

Dui2. press. . .0 



